Cancel shipment

In this section, you will find the explanation of how to cancel a shipment.

Cancel shipment request

To cancel a shipment, you need to send a POST request to the endpoint /api/Carriers/[CARRIER_ID]/cancelShipment/:trackingNumber with the following body:

Request body

{
  "cancelReason": "string",
  "destroyPackage": "boolean",
  "returnToSender": "boolean"
}

Field	Type	Format	Description
cancelReason	OPTIONAL	string	The reason for the cancellation
destroyPackage	OPTIONAL	boolean	Whether the package should be destroyed
returnToSender	OPTIONAL	boolean	Whether the package should be returned to the sender

Important

Shipments maybe canceled if they are in the ADDED state else they are charged.

An example of a request:

cURL

curl --location 'https://alphadev-api.peddler.com/api/Carriers/[CARRIER_ID]/cancelShipment/P123456789012345678' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <bearer-token-here>' \
--data '{
    "cancelReason": "Customer requested to receive a new variant"
}'

JavaScript

Cancel shipment

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://alphadev-api.peddler.com/api/Carriers/[CARRIER_ID]/cancelShipment/P123456789012345678',
  'headers': {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Bearer <bearer-token-here>'
  },
  body: JSON.stringify({
    "cancelReason": "Customer requested to receive a new variant"
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Cancel shipment response

A standard response will be a 200 status code with the following body:

Response body with 200 status

{
    "status": "<string>",
    "count": "<number>"
}

Field	Type	Description
status	string	The status of the cancellation
count	number	The number of shipments canceled

An example response body:

Response body example

{
    "status": "SUCCESS",
    "count": 1
}

The response will be a 404 status code with the following body if the tracking number is not valid or doesn't exist:

Response body with 404 status

{
    "error": {
        "statusCode": 404,
        "name": "tracking-number-not-found",
        "message": "TRACKING NUMBER NOT FOUND"
    }
}

Field	Type	Description
statusCode	string	The status of the cancellation
name	string	The details of the cancellation
message	string	The message of the cancellation

Important

The shipment cannot be cancel if it is in the DELIVERED or OUT_FOR_DELIVERY state. In such a case, you will receive the following as response:

Response body with 422 status

{
    "error": {
        "statusCode": 422,
        "name": "shipment-status-does-not-allow-cancelation",
        "message": "SHIPMENT STATUS DOES NOT ALLOW CANCELATION"
    }
}